home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.2 Development Libraries / SGI IRIX 6.2 Development Libraries.iso / dist / complib.idb / usr / share / catman / p_man / cat3 / complib / cggbal.z / cggbal
Text File  |  1996-03-14  |  5KB  |  133 lines
  1.  
  2.  
  3.  
  4. CCCCGGGGGGGGBBBBAAAALLLL((((3333FFFF))))                                                          CCCCGGGGGGGGBBBBAAAALLLL((((3333FFFF))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      CGGBAL - balance a pair of general complex matrices (A,B)
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      SUBROUTINE CGGBAL( JOB, N, A, LDA, B, LDB, ILO, IHI, LSCALE, RSCALE,
  13.                         WORK, INFO )
  14.  
  15.          CHARACTER      JOB
  16.  
  17.          INTEGER        IHI, ILO, INFO, LDA, LDB, N
  18.  
  19.          REAL           LSCALE( * ), RSCALE( * ), WORK( * )
  20.  
  21.          COMPLEX        A( LDA, * ), B( LDB, * )
  22.  
  23. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  24.      CGGBAL balances a pair of general complex matrices (A,B).  This involves,
  25.      first, permuting A and B by similarity transformations to isolate
  26.      eigenvalues in the first 1 to ILO$-$1 and last IHI+1 to N elements on the
  27.      diagonal; and second, applying a diagonal similarity transformation to
  28.      rows and columns ILO to IHI to make the rows and columns as close in norm
  29.      as possible. Both steps are optional.
  30.  
  31.      Balancing may reduce the 1-norm of the matrices, and improve the accuracy
  32.      of the computed eigenvalues and/or eigenvectors in the generalized
  33.      eigenvalue problem A*x = lambda*B*x.
  34.  
  35.  
  36. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  37.      JOB     (input) CHARACTER*1
  38.              Specifies the operations to be performed on A and B:
  39.              = 'N':  none:  simply set ILO = 1, IHI = N, LSCALE(I) = 1.0 and
  40.              RSCALE(I) = 1.0 for i=1,...,N; = 'P':  permute only;
  41.              = 'S':  scale only;
  42.              = 'B':  both permute and scale.
  43.  
  44.      N       (input) INTEGER
  45.              The order of the matrices A and B.  N >= 0.
  46.  
  47.      A       (input/output) COMPLEX array, dimension (LDA,N)
  48.              On entry, the input matrix A.  On exit, A is overwritten by the
  49.              balanced matrix.  If JOB = 'N', A is not referenced.
  50.  
  51.      LDA     (input) INTEGER
  52.              The leading dimension of the array A. LDA >= max(1,N).
  53.  
  54.      B       (input/output) COMPLEX array, dimension (LDB,N)
  55.              On entry, the input matrix B.  On exit, B is overwritten by the
  56.              balanced matrix.  If JOB = 'N', B is not referenced.
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. CCCCGGGGGGGGBBBBAAAALLLL((((3333FFFF))))                                                          CCCCGGGGGGGGBBBBAAAALLLL((((3333FFFF))))
  71.  
  72.  
  73.  
  74.      LDB     (input) INTEGER
  75.              The leading dimension of the array B. LDB >= max(1,N).
  76.  
  77.      ILO     (output) INTEGER
  78.              IHI     (output) INTEGER ILO and IHI are set to integers such
  79.              that on exit A(i,j) = 0 and B(i,j) = 0 if i > j and j =
  80.              1,...,ILO-1 or i = IHI+1,...,N.  If JOB = 'N' or 'S', ILO = 1 and
  81.              IHI = N.
  82.  
  83.      LSCALE  (output) REAL array, dimension (N)
  84.              Details of the permutations and scaling factors applied to the
  85.              left side of A and B.  If P(j) is the index of the row
  86.              interchanged with row j, and D(j) is the scaling factor applied
  87.              to row j, then LSCALE(j) = P(j)    for J = 1,...,ILO-1 = D(j)
  88.              for J = ILO,...,IHI = P(j)    for J = IHI+1,...,N.  The order in
  89.              which the interchanges are made is N to IHI+1, then 1 to ILO-1.
  90.  
  91.      RSCALE  (output) REAL array, dimension (N)
  92.              Details of the permutations and scaling factors applied to the
  93.              right side of A and B.  If P(j) is the index of the column
  94.              interchanged with column j, and D(j) is the scaling factor
  95.              applied to column j, then RSCALE(j) = P(j)    for J = 1,...,ILO-1
  96.              = D(j)    for J = ILO,...,IHI = P(j)    for J = IHI+1,...,N.  The
  97.              order in which the interchanges are made is N to IHI+1, then 1 to
  98.              ILO-1.
  99.  
  100.      WORK    (workspace) REAL array, dimension (6*N)
  101.  
  102.      INFO    (output) INTEGER
  103.              = 0:  successful exit
  104.              < 0:  if INFO = -i, the i-th argument had an illegal value.
  105.  
  106. FFFFUUUURRRRTTTTHHHHEEEERRRR DDDDEEEETTTTAAAAIIIILLLLSSSS
  107.      See R.C. WARD, Balancing the generalized eigenvalue problem,
  108.                     SIAM J. Sci. Stat. Comp. 2 (1981), 141-152.
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.